% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/country_date.R
\name{stretch}
\alias{stretch}
\title{Expand based on row.names}
\usage{
stretch(x, by, gaps = TRUE, preserve.na = TRUE, interpolate = FALSE)
}
\arguments{
\item{x}{Matrix to expand.}

\item{by}{CharacterVector of country-dates to expand by.}

\item{gaps}{Logical, whether to preserve gaps when expanding.}

\item{preserve.na}{Logical, whether to preserve NA from the original
matrix, \code{x}.}

\item{interpolate}{Logical, whether to first interpolate each year
before filling in missing values in the expanded matrix.}
}
\description{
\code{stretch} expands a matrix row-wise by a given character
vector of country-dates. For example, it can be used to expand a
country-date reduced matrix to the full time series.
}
\details{
Given a matrix, \code{x}, with country-date rownames and a
    character vector of country-dates that should be added
    (\emph{i.e.,} expanded to), \code{stretch} will output a matrix
    with \code{ncol(x)} columns and \code{length(union(by,
    rownames(x)))} rows. The rows shared between the output matrix
    and \code{x} will be filled in with the values from \code{x}
    before calling \code{\link{locf}}.

    Missingness will be filled in by \code{country_text_id}, sorted
    by \code{historical_date}. If \code{gaps} is \code{TRUE}, gaps
    will be preserved such that if there is more than a 365 day
    difference between two observations, the last observation will
    not be carried forward.

    When \code{preserve.na} is \code{TRUE}, \code{NA} in the
    original matrix, \code{x}, will be preserved and propagated in
    the output matrix.

    If \code{interpolate} is \code{TRUE}, before calling
    \code{\link{locf}}, values in the output matrix will be first
    interpolated per country-year using the
    \code{\link{interpolate}} --- specifically, this means that if
    there's a single non-missing observation on "12-31", the year
    will first be backfilled.
}
\examples{
m <- matrix(1:2, 2, 1, dimnames = list(c("AFG 1790-12-31", "AFG 1791-12-31"),
                                       NULL))

full_names <- c("AFG 1790-12-31", "AFG 1791-05-04",
                "AFG 1791-12-31", "AFG 1795-12-31")

stretch(m, full_names)

# Expand with interpolation
stretch(m, full_names, interpolate = TRUE)

# Ignore gaps
stretch(m, full_names, gaps = FALSE)

}
\seealso{
Other fill functions: \code{\link{interpolate}},
  \code{\link{locf}}
}
\concept{fill functions}
